package org.cloudie.docs.editor.client.feeds.docs;

import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * The GData remote service.
 */
@RemoteServiceRelativePath("doc-rpc")
public interface FileService extends RemoteService {
  
  /**
   * Retrieves a file by Id.
   * 
   * @param fileId the file Id
   * @return the file entry
   * @throws FileServiceException
   */
  FileServiceEntry getFile(String fileId) throws FileServiceException;
  
  /**
   * Retrieves a new, unsaved, file.
   * 
   * @param name the new file's name
   * @return the new document reference
   */
  FileServiceEntry getNewFile(String name);
  
  /**
   * Retrieves the contents of a document by resource Id.
   * 
   * @param resourceId the resource Id
   * @return the document contents
   * @throws FileServiceException
   */
  String getDocumentContents(String resourceId) throws FileServiceException;
  
  /**
   * Retrieves the contents of a spreadsheet by resource Id.
   * 
   * @param resourceId the resource Id
   * @return the spreadsheet contents
   * @throws FileServiceException
   */
  String getSpreadsheetContents(String resourceId) throws FileServiceException;
  
  /**
   * Retrieves the contents of a common document.
   * 
   * @param name the name of the document whose documents to retrieve
   * @return the document's contents
   */
  String getCommonContents(String name);
  
  /**
   * Updates the contents of a document.
   * 
   * @param documentId the document Id
   * @param etag the document's version tag
   * @param contents the document contents
   * @return whether the update was successful
   * @throws FileServiceException
   */
  FileServiceEntry setDocumentContents(String documentId, String etag, String contents) throws FileServiceException;
  
  /**
   * Updates the contents of a spreadsheet.
   * 
   * @param spreadsheetId the spreadsheet Id
   * @param etag the document's version tag
   * @param contents the spreadsheet contents
   * @return whether the updated entry
   * @throws FileServiceException
   */
  FileServiceEntry setSpreadsheetContents(String spreadsheetId, String etag, String contents) throws FileServiceException;
  
  /**
   * Renames a file.
   * 
   * @param fileId the file Id
   * @param newName the new file name
   * @return the updated file
   * @throws FileServiceException
   */
  FileServiceEntry renameFile(String fileId, String newName) throws FileServiceException;
  
  /**
   * Deletes a file.
   * 
   * @param fileId the file Id
   * @param etag the file's version tag
   * @return whether the delete was successful
   * @throws FileServiceException
   */
  boolean deleteFile(String fileId, String etag) throws FileServiceException;
  
  /**
   * Sets whether a file is starred.
   * 
   * @param fileId the file Id
   * @param starred whether the file is starred
   * @return whether the starring was successful
   * @throws FileServiceException
   */
  boolean setFileStarred(String fileId, boolean starred) throws FileServiceException;
  
  /**
   * Creates a new, saved, document.
   * 
   * @param title the document's title
   * @param contents the document's contents
   * @return the new document entry
   * @throws FileServiceException
   */
  FileServiceEntry createDocument(String title, String contents) throws FileServiceException;
  /**
   * Creates a new, saved, spreadsheet.
   * 
   * @param title the spreadsheet's title
   * @param contents the spreadsheet's contents
   * @return the new spreadsheet entry
   * @throws FileServiceException
   */
  FileServiceEntry createSpreadsheet(String title, String contents) throws FileServiceException;
  
  /**
   * Updates or creates a new document. If a value for documentId is
   * specified, the respective document is updated, otherwise a new 
   * document is created.
   * 
   * @param documentId the document Id
   * @param etag the document's etag
   * @param title the document's title
   * @param contents the document's contents
   * @return the new or updated document reference
   * @throws FileServiceException
   */
  FileServiceEntry saveDocument(String documentId, String etag, String title, String contents) throws FileServiceException;
  
  /**
   * Updates or creates a new spreadsheet. If a value for spreadsheetId is
   * specified, the respective spreadsheet is updated, otherwise a new 
   * spreadsheet is created.
   * 
   * @param spreadsheetId the spreadsheet Id
   * @param etag the spreadsheet's etag
   * @param title the spreadsheet's title
   * @param contents the spreadsheet's contents
   * @return the new or updated spreadsheet reference
   * @throws FileServiceException
   */
  FileServiceEntry saveSpreadsheet(String spreadsheetId, String etag, String title, String contents) throws FileServiceException;
  
  /**
   * Retrieves a list of a files.
   * 
   * @param starredOnly whether to return only starred files
   * @param searchTerm the term to search for in the file contents
   * @return the list of file entries
   * @throws FileServiceException
   */
  FileServiceEntry[] getFiles(boolean starredOnly, String searchTerm) throws FileServiceException;
  
  /**
   * Retrieves the currently signed on user.
   * 
   * @return the current user's name
   */
  FileUser getUser();
  
  FileUser setUser(String email, String token);
  
  /**
   * Ends the current user's session
   * 
   * @return the URL to which the user should be redirected in order
   * to complete the sign off process
   * @throws FileServiceException
   */
  String logout() throws FileServiceException;
}
